Welcome to binary_c-python’s documentation!
Python module for binary_c
We present our package binary_c-python, a population synthesis code which is aimed to provide a convenient and easy-to-use interface to the binary_c framework, allowing the user to rapidly evolve single stellar systems and populations of star systems. Based on earlier Perl versions by Robert Izzard, updated and extended for Python 3 by David Hendriks, Robert Izzard. Credits to Jeff Andrews for early efforts on the python-c interface.
binary_c-python is developed for students and scientists in the field of stellar astrophysics, who want to study the evolution of individual or populations of single and binary star systems (see the example use-case notebooks in the online documentation).
Below we provide the installation instructions for
To run this code you need to at least have installations of:
Pythonversion 3.9 up to 3.12 (it’s recommended to use Pyenv to manage your Python versions)
binary_cversion 2.2.4 (See installation section)
The Python packages that are required for this code to run are listed in the
requirements.txt, which automatically gets read out by
To build the documentation the following additional software is required:
pandocavailable on https://pandoc.org/ or via
sudo apt-get install pandoc
binary_c-python please make sure to have defined the following environment variables:
BINARY_Cshould point to the root directory of your binary_c installation
LD_LIBRARY_PATHshould include $BINARY_C/src and whatever directories are required to run binary_c (e.g. locations of libgsl, libmemoize, librinterpolate, etc.)
LIBRARY_PATHshould include whatever directories are required to build binary_c (e.g. locations of libgsl, libmemoize, librinterpolate, etc.)
GSL_DIRshould point to the root location where you installed GSL to. This root dir should contain
There are several ways to install
Installation via PIP:
To install this package via pip:
pip install binarycpython
This will install the latest stable installation that is available on Pip. The version on the master branch of
binary_c-python is the same version as the latest stable version on Pip.
Installation from source:
To install the
binary_c-python from source, which is useful for development versions and customisation, run
This will install the package, along with all the dependencies, into the current active (virtual) python environment.
Use of code without installation
It is possible to use parts of the code without installing it, by adding the root directory of this repo to your
binary_c-python, via e.g.
git clone https://gitlab.com/binary_c/binary_c-python.git
Add the path to the downloaded repo to your
$PYTHONPATH, via e.g.
It will not be possible to actually run systems through
The documentation for the latest stable release of
binary_c-python is available on https://binary_c.gitlab.io/binary_c-python/.
The documentation for
binary_c is available on https://binary_c.gitlab.io/binary_c.
Make sure that with every change/recompilation you make in
binary_c, you also rebuild
binary_c-python. Whenever you change the source code of this package, you need to re-install it into your virtualenvironment as well.
binary_c-python from source you can run the unit tests to make sure the code works as it should.
There are two suites of unit tests for
binary_c-python. The first includes only the actual code of the project, and is located at
binarycpython/test/main.py. The second includes only the tutorial and example notebooks, and is located at
If you want to contribute to the code, then it is recommended that you install the packages in
pip install -r development_requirements.txt
Please do not hesitate to contact us to discuss any contribution. Please see
Some useful commands to generate documentation and coverage reports are stored in the
We use the following naming convention for development and release branches:
development/<binary_c-python version>/<binary_c version> releases/<binary_c-python version>/<binary_c version>
To build the documentation manually, run
from within the
commands/ directory. Note: this requires
pandoc to be installed on your machine.
Generating docstring and test coverage report
To generate the unit test and docstring coverage report, run
from within the
We’ve written a JOSS paper for
binary_c-python, which is stored in papers/joss/paper.pdf.
Paper review status:
If you encounter an issue with the code, or if you want to suggest extra features or changes in the code, please submit an issue at https://gitlab.com/binary_c/binary_c-python/-/issues/new.
Here we provide a non-exhaustive list of some issues we encountered and solutions for these:
Building issues with binary_c itself:
see the documentation of binary_c (in doc/).
If you have MESA installed, make sure that the
$MESASDK_ROOT/bin/mesasdk_init.shis not sourced. It comes with its own version of some programs, and those can interfere with installing.
When Pip install fails:
Run the installation with
--log <logfile>to get some more info
If gcc throws errors like
gcc: error: unrecognized command line option ‘-ftz’; did you mean ‘-flto’?, this might be due to that the python on that system was built with a different compiler. It then passes the python3.6-config –cflags to the binarycpython installation, which, if done with gcc, will not work. Try a different python3.6. I suggest using
pyenvto manage python versions. If installing a version of python with pyenv is not possible, then try to use a python version that is avaible to the machine that is built with the same compiler as binary_c was built with.
if pip installation results in
No files/directories in /tmp/pip-1ckzg0p9-build/pip-egg-info (from PKG-INFO), try running it verbose (
-v) to see what is actually going wrong.
If pip terminates with the error FileNotFoundError: [Errno 2] No such file or directory: ‘<…>/binary_c-config’ Then make sure that the path to your main $BINARY_C directory is set correctly.
When running jupyter notebooks, make sure you are running the jupyter installation from the same virtual environment.
When the output of binary_c seems to be different than expected, you might need to rebuild this python package. Everytime binary_c is compiled, this package needs to be rebuilt too.
- Python module for binary_c
- Example notebooks
- Tutorial: Running individual systems with binary_c-python
- Tutorial: Using custom logging routines with binary_c-python
- Tutorial: Running populations with binary_c-python (grid sampling)
- Tutorial: Using the API functionality of binary_c-python
- Tutorial: Generating and handling ensemble data
- Tutorial: Event based logging output
- Tutorial: Running populations with binary_c-python with a source file
- Example use case: Zero-age stellar luminosity function
- Example use case: Zero-age stellar luminosity function in binaries
- Example use case: Hertzsprung-Russell diagrams
- Example use case: Common-envelope evolution
- Example use case: Binary black hole systems
- Example use case: Solar system using the API functionality
- Event based logging
- Population options
- Binary_c parameters
- Binary_c-python code
- custom_logging_functions module
- dicts module
- Email module
- ensemble module
- event logging module
- functions module
- logging module
- Population class module
- plot_functions module
- Population class extension: analytics module
- Population class extension: argument handling module
- Population class extension: cache module
- Population class extension: condor module
- Population class extension: custom binary_c logging sampling module
- Population class extension: custom generator sampling module
- Population class extension: dataIO module
- Population class extension: distribution_functions module
- Population class extension: email functions module
- Population class extension: ensemble functions module
- Population class extension: evolution functions module
- Population class extension: failing systems functions module
- Population class extension: grid_logging module
- Population class extension: grid sampling functions module
- Population class extension: HPC module
- Population class extension: logging module
- Population class extension: metadata module
- Population class extension: miscellaneous functions module
- Population class extension: Moe_di_Stefano_2017 module
- Population class extension: Monte-Carlo sampling functions module
- Population class extension: population_options_defaults module
- Population class extension: return functions module
- Population class extension: sampling variables functions module
- Population class extension: signal handling functions module
- Population class extension: slurm module
- Population class extension: source file sampling functions module
- Population class extension: spacing_functions module
- Population class extension: termination functions module
- Population class extension: version_info module
- run_system_wrapper module
- stellar_types module
- useful_funcs module
- Visit the GitLab repo
- Submit an issue